home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 April: Mac OS SDK / Dev.CD Apr 99 SDK1.toast / Development Kits / Interfaces&Libraries / Universal / Interfaces / CIncludes / NameRegistry.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-17  |  13.5 KB  |  494 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        NameRegistry.h
  3.  
  4.      Contains:    NameRegistry Interfaces
  5.  
  6.      Version:    Technology:    MacOS
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1993-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __NAMEREGISTRY__
  18. #define __NAMEREGISTRY__
  19.  
  20. #ifndef __MACTYPES__
  21. #include <MacTypes.h>
  22. #endif
  23.  
  24.  
  25.  
  26. #if PRAGMA_ONCE
  27. #pragma once
  28. #endif
  29.  
  30. #ifdef __cplusplus
  31. extern "C" {
  32. #endif
  33.  
  34. #if PRAGMA_IMPORT
  35. #pragma import on
  36. #endif
  37.  
  38. #if PRAGMA_STRUCT_ALIGN
  39.     #pragma options align=power
  40. #elif PRAGMA_STRUCT_PACKPUSH
  41.     #pragma pack(push, 2)
  42. #elif PRAGMA_STRUCT_PACK
  43.     #pragma pack(2)
  44. #endif
  45.  
  46. /*******************************************************************************
  47.  * 
  48.  * Foundation Types
  49.  *
  50.  */
  51. /* Value of a property */
  52. typedef void *                            RegPropertyValue;
  53. /* Length of property value */
  54. typedef UInt32                             RegPropertyValueSize;
  55. /*******************************************************************************
  56.  * 
  57.  * RegEntryID    :    The Global x-Namespace Entry Identifier
  58.  *
  59.  */
  60.  
  61. struct RegEntryID {
  62.     UInt32                             contents[4];
  63. };
  64. typedef struct RegEntryID                RegEntryID;
  65. typedef RegEntryID *                    RegEntryIDPtr;
  66. /*******************************************************************************
  67.  *
  68.  * Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  69.  *
  70.  *    • Names are a colon-separated list of name components.  Name components
  71.  *      may not themselves contain colons.  
  72.  *    • Names are presented as null-terminated ASCII character strings.
  73.  *    • Names follow similar parsing rules to Apple file system absolute
  74.  *      and relative paths.  However the '::' parent directory syntax is
  75.  *      not currently supported.
  76.  */
  77. /* Max length of Entry Name */
  78.  
  79. enum {
  80.     kRegCStrMaxEntryNameLength    = 47
  81. };
  82.  
  83. /* Entry Names are single byte ASCII */
  84.  
  85. typedef char                             RegCStrEntryName;
  86. typedef char *                            RegCStrEntryNamePtr;
  87. /* length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1*/
  88. typedef char                             RegCStrEntryNameBuf[48];
  89. typedef char                             RegCStrPathName;
  90. typedef UInt32                             RegPathNameSize;
  91.  
  92. enum {
  93.     kRegPathNameSeparator        = ':',                            /* 0x3A */
  94.     kRegEntryNameTerminator        = 0x00,                            /* '\0' */
  95.     kRegPathNameTerminator        = 0x00                            /* '\0' */
  96. };
  97.  
  98. /*******************************************************************************
  99.  *
  100.  * Property Name and ID Definitions
  101.  *    (Applies to all Properties Regardless of NameSpace)
  102.  */
  103.  
  104. enum {
  105.     kRegMaximumPropertyNameLength = 31,                            /* Max length of Property Name */
  106.     kRegPropertyNameTerminator    = 0x00                            /* '\0' */
  107. };
  108.  
  109. typedef char                             RegPropertyNameBuf[32];
  110. typedef char                             RegPropertyName;
  111. typedef char *                            RegPropertyNamePtr;
  112. /*******************************************************************************
  113.  *
  114.  * Iteration Operations
  115.  *
  116.  *    These specify direction when traversing the name relationships
  117.  */
  118. typedef UInt32                             RegIterationOp;
  119. typedef RegIterationOp                     RegEntryIterationOp;
  120.  
  121. enum {
  122.                                                                 /* Absolute locations*/
  123.     kRegIterRoot                = 0x00000002,                    /* "Upward" Relationships    */
  124.     kRegIterParents                = 0x00000003,                    /* include all  parent(s) of entry */
  125.                                                                 /* "Downward" Relationships*/
  126.     kRegIterChildren            = 0x00000004,                    /* include all children */
  127.     kRegIterSubTrees            = 0x00000005,                    /* include all sub trees of entry */
  128.     kRegIterDescendants            = 0x00000005,                    /* include all descendants of entry */
  129.                                                                 /* "Horizontal" Relationships    */
  130.     kRegIterSibling                = 0x00000006,                    /* include all siblings */
  131.                                                                 /* Keep doing the same thing*/
  132.     kRegIterContinue            = 0x00000001
  133. };
  134.  
  135. /*******************************************************************************
  136.  *
  137.  * Name Entry and Property Modifiers
  138.  *
  139.  *
  140.  *
  141.  * Modifiers describe special characteristics of names
  142.  * and properties.  Modifiers might be supported for
  143.  * some names and not others.
  144.  * 
  145.  * Device Drivers should not rely on functionality
  146.  * specified as a modifier.
  147.  */
  148. typedef UInt32                             RegModifiers;
  149. typedef RegModifiers                     RegEntryModifiers;
  150. typedef RegModifiers                     RegPropertyModifiers;
  151.  
  152. enum {
  153.     kRegNoModifiers                = 0x00000000,                    /* no entry modifiers in place */
  154.     kRegUniversalModifierMask    = 0x0000FFFF,                    /* mods to all entries */
  155.     kRegNameSpaceModifierMask    = 0x00FF0000,                    /* mods to all entries within namespace */
  156.     kRegModifierMask            = (long)0xFF000000                /* mods to just this entry */
  157. };
  158.  
  159. /* Universal Property Modifiers */
  160.  
  161. enum {
  162.     kRegPropertyValueIsSavedToNVRAM = 0x00000020,                /* property is non-volatile (saved in NVRAM) */
  163.     kRegPropertyValueIsSavedToDisk = 0x00000040                    /* property is non-volatile (saved on disk) */
  164. };
  165.  
  166. /* ///////////////////////
  167. //
  168. // The Registry API
  169. //
  170. /////////////////////// */
  171. /* ///////////////////////
  172. //
  173. // Entry Management
  174. //
  175. /////////////////////// */
  176.  
  177. /*-------------------------------
  178.  * EntryID handling
  179.  */
  180. /*
  181.  * Initialize an EntryID to a known invalid state
  182.  *   note: invalid != uninitialized
  183.  */
  184. EXTERN_API_C( OSStatus )
  185. RegistryEntryIDInit                (RegEntryID *            id);
  186.  
  187. /*
  188.  * Compare EntryID's for equality or if invalid
  189.  *
  190.  * If a NULL value is given for either id1 or id2, the other id 
  191.  * is compared with an invalid ID.  If both are NULL, the id's 
  192.  * are consided equal (result = true). 
  193.  */
  194. EXTERN_API_C( Boolean )
  195. RegistryEntryIDCompare            (const RegEntryID *        id1,
  196.                                  const RegEntryID *        id2);
  197.  
  198. /*
  199.  * Copy an EntryID
  200.  */
  201. EXTERN_API_C( OSStatus )
  202. RegistryEntryIDCopy                (const RegEntryID *        src,
  203.                                  RegEntryID *            dst);
  204.  
  205. /*
  206.  * Free an ID so it can be reused.
  207.  */
  208. EXTERN_API_C( OSStatus )
  209. RegistryEntryIDDispose            (RegEntryID *            id);
  210.  
  211. /*-------------------------------
  212.  * Adding and removing entries
  213.  *
  214.  * If (parentEntry) is NULL, the name is assumed
  215.  * to be a rooted path. It is rooted to an anonymous, unnamed root.
  216.  */
  217. EXTERN_API_C( OSStatus )
  218. RegistryCStrEntryCreate            (const RegEntryID *        parentEntry,
  219.                                  const RegCStrPathName * name,
  220.                                  RegEntryID *            newEntry);
  221.  
  222. EXTERN_API_C( OSStatus )
  223. RegistryEntryDelete                (const RegEntryID *        id);
  224.  
  225. EXTERN_API_C( OSStatus )
  226. RegistryEntryCopy                (RegEntryID *            parentEntryID,
  227.                                  RegEntryID *            sourceDevice,
  228.                                  RegEntryID *            destDevice);
  229.  
  230. /*---------------------------
  231.  * Traversing the namespace
  232.  *
  233.  * To support arbitrary namespace implementations in the future,
  234.  * I have hidden the form that the place pointer takes.  The previous
  235.  * interface exposed the place pointer by specifying it as a
  236.  * RegEntryID.
  237.  *
  238.  * I have also removed any notion of returning the entries
  239.  * in a particular order, because an implementation might
  240.  * return the names in semi-random order.  Many name service
  241.  * implementations will store the names in a hashed lookup
  242.  * table.
  243.  *
  244.  * Writing code to traverse some set of names consists of
  245.  * a call to begin the iteration, the iteration loop, and
  246.  * a call to end the iteration.  The begin call initializes
  247.  * the iteration cookie data structure.  The call to end the 
  248.  * iteration should be called even in the case of error so 
  249.  * that allocated data structures can be freed.
  250.  *
  251.  *    Create(...)
  252.  *    do {
  253.  *        Iterate(...);
  254.  *    } while (!done);
  255.  *    Dispose(...);
  256.  *
  257.  * This is the basic code structure for callers of the iteration
  258.  * interface.
  259.  */
  260. typedef struct OpaqueRegEntryIter*         RegEntryIter;
  261. /* 
  262.  * create/dispose the iterator structure
  263.  *   defaults to root with relationship = kRegIterDescendants
  264.  */
  265. EXTERN_API_C( OSStatus )
  266. RegistryEntryIterateCreate        (RegEntryIter *            cookie);
  267.  
  268. EXTERN_API_C( OSStatus )
  269. RegistryEntryIterateDispose        (RegEntryIter *            cookie);
  270.  
  271. /* 
  272.  * set Entry Iterator to specified entry
  273.  */
  274. EXTERN_API_C( OSStatus )
  275. RegistryEntryIterateSet            (RegEntryIter *            cookie,
  276.                                  const RegEntryID *        startEntryID);
  277.  
  278. /*
  279.  * Return each value of the iteration
  280.  *
  281.  * return entries related to the current entry
  282.  * with the specified relationship
  283.  */
  284. EXTERN_API_C( OSStatus )
  285. RegistryEntryIterate            (RegEntryIter *            cookie,
  286.                                  RegEntryIterationOp     relationship,
  287.                                  RegEntryID *            foundEntry,
  288.                                  Boolean *                done);
  289.  
  290. /*
  291.  * return entries with the specified property
  292.  *
  293.  * A NULL RegPropertyValue pointer will return an
  294.  * entry with the property containing any value.
  295.  */
  296. EXTERN_API_C( OSStatus )
  297. RegistryEntrySearch                (RegEntryIter *            cookie,
  298.                                  RegEntryIterationOp     relationship,
  299.                                  RegEntryID *            foundEntry,
  300.                                  Boolean *                done,
  301.                                  const RegPropertyName * propertyName,
  302.                                  const void *            propertyValue,
  303.                                  RegPropertyValueSize     propertySize);
  304.  
  305. /*--------------------------------
  306.  * Find a name in the namespace
  307.  *
  308.  * This is the fast lookup mechanism.
  309.  * NOTE:  A reverse lookup mechanism
  310.  *      has not been provided because
  311.  *        some name services may not
  312.  *        provide a fast, general reverse
  313.  *        lookup.
  314.  */
  315. EXTERN_API_C( OSStatus )
  316. RegistryCStrEntryLookup            (const RegEntryID *        searchPointID,
  317.                                  const RegCStrPathName * pathName,
  318.                                  RegEntryID *            foundEntry);
  319.  
  320. /*---------------------------------------------
  321.  * Convert an entry to a rooted name string
  322.  *
  323.  * A utility routine to turn an Entry ID
  324.  * back into a name string.
  325.  */
  326. EXTERN_API_C( OSStatus )
  327. RegistryEntryToPathSize            (const RegEntryID *        entryID,
  328.                                  RegPathNameSize *        pathSize);
  329.  
  330. EXTERN_API_C( OSStatus )
  331. RegistryCStrEntryToPath            (const RegEntryID *        entryID,
  332.                                  RegCStrPathName *        pathName,
  333.                                  RegPathNameSize         pathSize);
  334.  
  335. /*
  336.  * Parse a path name.
  337.  *
  338.  * Retrieve the last component of the path, and
  339.  * return a spec for the parent.
  340.  */
  341. EXTERN_API_C( OSStatus )
  342. RegistryCStrEntryToName            (const RegEntryID *        entryID,
  343.                                  RegEntryID *            parentEntry,
  344.                                  RegCStrEntryName *        nameComponent,
  345.                                  Boolean *                done);
  346.  
  347. /* //////////////////////////////////////////////////////
  348. //
  349. // Property Management
  350. //
  351. ////////////////////////////////////////////////////// */
  352. /*-------------------------------
  353.  * Adding and removing properties
  354.  */
  355. EXTERN_API_C( OSStatus )
  356. RegistryPropertyCreate            (const RegEntryID *        entryID,
  357.                                  const RegPropertyName * propertyName,
  358.                                  const void *            propertyValue,
  359.                                  RegPropertyValueSize     propertySize);
  360.  
  361. EXTERN_API_C( OSStatus )
  362. RegistryPropertyDelete            (const RegEntryID *        entryID,
  363.                                  const RegPropertyName * propertyName);
  364.  
  365. EXTERN_API_C( OSStatus )
  366. RegistryPropertyRename            (const RegEntryID *        entry,
  367.                                  const RegPropertyName * oldName,
  368.                                  const RegPropertyName * newName);
  369.  
  370. /*---------------------------
  371.  * Traversing the Properties of a name
  372.  *
  373.  */
  374. typedef struct OpaqueRegPropertyIter*     RegPropertyIter;
  375. EXTERN_API_C( OSStatus )
  376. RegistryPropertyIterateCreate    (const RegEntryID *        entry,
  377.                                  RegPropertyIter *        cookie);
  378.  
  379. EXTERN_API_C( OSStatus )
  380. RegistryPropertyIterateDispose    (RegPropertyIter *        cookie);
  381.  
  382. EXTERN_API_C( OSStatus )
  383. RegistryPropertyIterate            (RegPropertyIter *        cookie,
  384.                                  RegPropertyName *        foundProperty,
  385.                                  Boolean *                done);
  386.  
  387. /*
  388.  * Get the value of the specified property for the specified entry.
  389.  *
  390.  */
  391. EXTERN_API_C( OSStatus )
  392. RegistryPropertyGetSize            (const RegEntryID *        entryID,
  393.                                  const RegPropertyName * propertyName,
  394.                                  RegPropertyValueSize *    propertySize);
  395.  
  396. /*
  397.  * (*propertySize) is the maximum size of the value returned in the buffer
  398.  * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  399.  * value returned.
  400.  */
  401. EXTERN_API_C( OSStatus )
  402. RegistryPropertyGet                (const RegEntryID *        entryID,
  403.                                  const RegPropertyName * propertyName,
  404.                                  void *                    propertyValue,
  405.                                  RegPropertyValueSize *    propertySize);
  406.  
  407. EXTERN_API_C( OSStatus )
  408. RegistryPropertySet                (const RegEntryID *        entryID,
  409.                                  const RegPropertyName * propertyName,
  410.                                  const void *            propertyValue,
  411.                                  RegPropertyValueSize     propertySize);
  412.  
  413. /* //////////////////////////////////////////////////////
  414. //
  415. // Modifier Management
  416. //
  417. ////////////////////////////////////////////////////// */
  418. /*
  419.  * Modifiers describe special characteristics of names
  420.  * and properties.  Modifiers might be supported for
  421.  * some names and not others.
  422.  * 
  423.  * Device Drivers should not rely on functionality
  424.  * specified as a modifier.  These interfaces
  425.  * are for use in writing Experts.
  426.  */
  427. /*
  428.  * Get and Set operators for entry modifiers
  429.  */
  430. EXTERN_API_C( OSStatus )
  431. RegistryEntryGetMod                (const RegEntryID *        entry,
  432.                                  RegEntryModifiers *    modifiers);
  433.  
  434. EXTERN_API_C( OSStatus )
  435. RegistryEntrySetMod                (const RegEntryID *        entry,
  436.                                  RegEntryModifiers         modifiers);
  437.  
  438. /*
  439.  * Get and Set operators for property modifiers
  440.  */
  441. EXTERN_API_C( OSStatus )
  442. RegistryPropertyGetMod            (const RegEntryID *        entry,
  443.                                  const RegPropertyName * name,
  444.                                  RegPropertyModifiers *    modifiers);
  445.  
  446. EXTERN_API_C( OSStatus )
  447. RegistryPropertySetMod            (const RegEntryID *        entry,
  448.                                  const RegPropertyName * name,
  449.                                  RegPropertyModifiers     modifiers);
  450.  
  451. /*
  452.  * Iterator operator for entry modifier search
  453.  */
  454. EXTERN_API_C( OSStatus )
  455. RegistryEntryMod                (RegEntryIter *            cookie,
  456.                                  RegEntryIterationOp     relationship,
  457.                                  RegEntryID *            foundEntry,
  458.                                  Boolean *                done,
  459.                                  RegEntryModifiers         matchingModifiers);
  460.  
  461. /*
  462.  * Iterator operator for entries with matching 
  463.  * property modifiers
  464.  */
  465. EXTERN_API_C( OSStatus )
  466. RegistryEntryPropertyMod        (RegEntryIter *            cookie,
  467.                                  RegEntryIterationOp     relationship,
  468.                                  RegEntryID *            foundEntry,
  469.                                  Boolean *                done,
  470.                                  RegPropertyModifiers     matchingModifiers);
  471.  
  472.  
  473.  
  474. #if PRAGMA_STRUCT_ALIGN
  475.     #pragma options align=reset
  476. #elif PRAGMA_STRUCT_PACKPUSH
  477.     #pragma pack(pop)
  478. #elif PRAGMA_STRUCT_PACK
  479.     #pragma pack()
  480. #endif
  481.  
  482. #ifdef PRAGMA_IMPORT_OFF
  483. #pragma import off
  484. #elif PRAGMA_IMPORT
  485. #pragma import reset
  486. #endif
  487.  
  488. #ifdef __cplusplus
  489. }
  490. #endif
  491.  
  492. #endif /* __NAMEREGISTRY__ */
  493.  
  494.